Update Javadoc and apply a few code fixes

This commit is contained in:
JeremyStar™ 2024-07-11 04:17:03 +02:00
parent 10fa65b8e1
commit 9c1f5711a7
Signed by: JeremyStarTM
GPG key ID: E366BAEF67E4704D
13 changed files with 83 additions and 9 deletions

View file

@ -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.EngineCrashEvent;
import de.staropensource.sosengine.base.events.EngineShutdownEvent; import de.staropensource.sosengine.base.events.EngineShutdownEvent;
import de.staropensource.sosengine.base.events.LogEvent; 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.internal.events.InternalEngineShutdownEvent;
import de.staropensource.sosengine.base.logging.CrashHandler; import de.staropensource.sosengine.base.logging.CrashHandler;
import de.staropensource.sosengine.base.logging.Logger; import de.staropensource.sosengine.base.logging.Logger;
@ -93,6 +94,7 @@ public final class Engine implements SubsystemMainClass {
* Returns a list of all registered subsystems. * Returns a list of all registered subsystems.
* The list is sorted after initialization order. * The list is sorted after initialization order.
* *
* @return subsystem list
* @since 1-alpha1 * @since 1-alpha1
*/ */
@NotNull @NotNull
@ -304,6 +306,8 @@ public final class Engine implements SubsystemMainClass {
for (DependencyVector vector : resolver.resolve().getOrder()) // smol workaround for (DependencyVector vector : resolver.resolve().getOrder()) // smol workaround
order.add((DependencySubsystemVector) vector); order.add((DependencySubsystemVector) vector);
} catch (Throwable throwable) { } 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())); logger.crash("An error occurred trying to resolve subsystem dependencies: " + throwable.getClass().getName() + (throwable.getMessage() == null ? "" : ": " + throwable.getMessage()));
throw throwable; throw throwable;
} }

View file

@ -51,8 +51,9 @@ public interface SubsystemMainClass {
/** /**
* Returns the {@link DependencyVector} for this subsystem. * Returns the {@link DependencyVector} for this subsystem.
* *
* @see DependencyVector * @return {@link DependencyVector} for this subsystem
* @since 1-alpha1 * @since 1-alpha1
* @see DependencyVector
*/ */
@NotNull @NotNull
DependencyVector getDependencyVector(); DependencyVector getDependencyVector();

View file

@ -28,6 +28,13 @@ import de.staropensource.sosengine.base.types.versioning.VersioningSystem;
*/ */
@SuppressWarnings({ "unused" }) @SuppressWarnings({ "unused" })
public class IncompatibleVersioningSystemException extends Exception { 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) { public IncompatibleVersioningSystemException(VersioningSystem required, VersioningSystem found) {
super("The versioning system " + required + " is incompatible with " + found); super("The versioning system " + required + " is incompatible with " + found);
} }

View file

@ -30,8 +30,8 @@ import org.jetbrains.annotations.Nullable;
* *
* @since 1-alpha1 * @since 1-alpha1
*/ */
@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" })
@Getter @Getter
@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" })
public class InvalidVersionStringException extends Exception { public class InvalidVersionStringException extends Exception {
/** /**
* Contains the throwable supplied to the constructor. * Contains the throwable supplied to the constructor.
@ -45,7 +45,7 @@ public class InvalidVersionStringException extends Exception {
* @since 1-alpha1 * @since 1-alpha1
*/ */
@Nullable @Nullable
Throwable throwable; private final Throwable throwable;
/** /**
* Constructs this exception. * Constructs this exception.

View file

@ -35,11 +35,17 @@ import java.util.Map;
public class UnmetDependenciesException extends Exception { public class UnmetDependenciesException extends Exception {
/** /**
* Contains the unmet dependencies list supplied to the constructor. * Contains the unmet dependencies list supplied to the constructor.
* <p>
* 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 * @since 1-alpha1
* *
* -- GETTER -- * -- GETTER --
* Returns the unmet dependencies list supplied to the constructor. * Returns the unmet dependencies list supplied to the constructor.
* <p>
* 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 * @return unmet dependencies list
* @since 1-alpha1 * @since 1-alpha1
@ -47,6 +53,13 @@ public class UnmetDependenciesException extends Exception {
@NotNull @NotNull
private final Map<@NotNull DependencyVector, @NotNull String> unmetDependencies; 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) { public UnmetDependenciesException(@NotNull Map<@NotNull DependencyVector, @NotNull String> unmetDependencies) {
this.unmetDependencies = unmetDependencies; this.unmetDependencies = unmetDependencies;
} }

View file

@ -47,6 +47,7 @@ import java.util.List;
* *
* @since 1-alpha1 * @since 1-alpha1
*/ */
@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" })
public abstract class ShortcodeParserSkeleton { public abstract class ShortcodeParserSkeleton {
/** /**
* Logger instance. * Logger instance.
@ -60,6 +61,12 @@ public abstract class ShortcodeParserSkeleton {
* A list of components the parsed string is made out of. * A list of components the parsed string is made out of.
* *
* @since 1-alpha1 * @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 @NotNull
@Getter @Getter

View file

@ -26,8 +26,8 @@ import java.util.function.UnaryOperator;
/** /**
* An unmodifiable {@link ArrayList}. * An unmodifiable {@link ArrayList}.
* {@inheritDoc}
* *
* @param <E> contained type
* @since 1-alpha1 * @since 1-alpha1
*/ */
@SuppressWarnings({ "unused" }) @SuppressWarnings({ "unused" })

View file

@ -28,8 +28,9 @@ import java.util.function.BiFunction;
/** /**
* An unmodifiable {@link Map}. * An unmodifiable {@link Map}.
* {@inheritDoc}
* *
* @param <K> contained key type
* @param <V> contained value type
* @since 1-alpha1 * @since 1-alpha1
*/ */
@SuppressWarnings({ "unused" }) @SuppressWarnings({ "unused" })

View file

@ -28,8 +28,9 @@ import java.util.function.BiFunction;
/** /**
* An unmodifiable {@link Map}. * An unmodifiable {@link Map}.
* {@inheritDoc}
* *
* @param <K> contained key type
* @param <V> contained value type
* @since 1-alpha1 * @since 1-alpha1
*/ */
@SuppressWarnings({ "unused" }) @SuppressWarnings({ "unused" })

View file

@ -29,8 +29,8 @@ import java.util.function.UnaryOperator;
/** /**
* An unmodifiable {@link LinkedList}. * An unmodifiable {@link LinkedList}.
* {@inheritDoc}
* *
* @param <E> contained type
* @since 1-alpha1 * @since 1-alpha1
*/ */
@SuppressWarnings({ "unused" }) @SuppressWarnings({ "unused" })

View file

@ -33,6 +33,7 @@ public interface VersioningSystem {
/** /**
* Returns the name of this versioning system. * Returns the name of this versioning system.
* *
* @return name of this versioning system
* @since 1-alpha1 * @since 1-alpha1
*/ */
@NotNull @NotNull
@ -43,6 +44,7 @@ public interface VersioningSystem {
* *
* @param version the version to compare against * @param version the version to compare against
* @return smaller = {@code 0}, equal = {@code 1}, bigger = {@code 2} * @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 * @since 1-alpha1
*/ */
@Range(from = 0, to = 2) @Range(from = 0, to = 2)

View file

@ -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.dependency.DependencyVector;
import de.staropensource.sosengine.base.types.immutable.ImmutableArrayList; import de.staropensource.sosengine.base.types.immutable.ImmutableArrayList;
import de.staropensource.sosengine.base.types.immutable.ImmutableLinkedList; import de.staropensource.sosengine.base.types.immutable.ImmutableLinkedList;
import lombok.Getter;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
import java.util.*; import java.util.*;
@ -42,6 +43,20 @@ public final class DependencyResolver {
*/ */
List<DependencyVector> vectors = new ArrayList<>(); List<DependencyVector> 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. * Constructs this class.
*/ */
@ -51,10 +66,12 @@ public final class DependencyResolver {
* Adds a dependency vector. * Adds a dependency vector.
* *
* @param vector dependency vector to add * @param vector dependency vector to add
* @return itself
* @since 1-alpha1 * @since 1-alpha1
*/ */
public DependencyResolver addVector(@NotNull DependencyVector vector) { public DependencyResolver addVector(@NotNull DependencyVector vector) {
vectors.add(vector); vectors.add(vector);
resolved = false;
return this; return this;
} }
@ -62,10 +79,12 @@ public final class DependencyResolver {
* Adds multiple dependency vectors. * Adds multiple dependency vectors.
* *
* @param vectors dependency vectors to add * @param vectors dependency vectors to add
* @return itself
* @since 1-alpha1 * @since 1-alpha1
*/ */
public DependencyResolver addVectors(@NotNull DependencyVector[] vectors) { public DependencyResolver addVectors(@NotNull DependencyVector[] vectors) {
addVectors(Arrays.stream(vectors).toList()); addVectors(Arrays.stream(vectors).toList());
resolved = false;
return this; return this;
} }
@ -73,10 +92,12 @@ public final class DependencyResolver {
* Adds multiple dependency vectors. * Adds multiple dependency vectors.
* *
* @param vectors dependency vectors to add * @param vectors dependency vectors to add
* @return itself
* @since 1-alpha1 * @since 1-alpha1
*/ */
public DependencyResolver addVectors(@NotNull Collection<? extends @NotNull DependencyVector> vectors) { public DependencyResolver addVectors(@NotNull Collection<? extends @NotNull DependencyVector> vectors) {
this.vectors.addAll(vectors); this.vectors.addAll(vectors);
resolved = false;
return this; return this;
} }
@ -84,10 +105,12 @@ public final class DependencyResolver {
* Adds multiple dependency vectors. * Adds multiple dependency vectors.
* *
* @param vectors dependency vectors to add * @param vectors dependency vectors to add
* @return itself
* @since 1-alpha1 * @since 1-alpha1
*/ */
public DependencyResolver addVectors(@NotNull List<? extends @NotNull DependencyVector> vectors) { public DependencyResolver addVectors(@NotNull List<? extends @NotNull DependencyVector> vectors) {
this.vectors.addAll(vectors); this.vectors.addAll(vectors);
resolved = false;
return this; return this;
} }
@ -95,10 +118,12 @@ public final class DependencyResolver {
* Adds multiple dependency vectors. * Adds multiple dependency vectors.
* *
* @param vectors dependency vectors to add * @param vectors dependency vectors to add
* @return itself
* @since 1-alpha1 * @since 1-alpha1
*/ */
public DependencyResolver addVectors(@NotNull ImmutableArrayList<? extends @NotNull DependencyVector> vectors) { public DependencyResolver addVectors(@NotNull ImmutableArrayList<? extends @NotNull DependencyVector> vectors) {
this.vectors.addAll(vectors); this.vectors.addAll(vectors);
resolved = false;
return this; return this;
} }
@ -106,10 +131,12 @@ public final class DependencyResolver {
* Adds multiple dependency vectors. * Adds multiple dependency vectors.
* *
* @param vectors dependency vectors to add * @param vectors dependency vectors to add
* @return itself
* @since 1-alpha1 * @since 1-alpha1
*/ */
public DependencyResolver addVectors(@NotNull ImmutableLinkedList<? extends @NotNull DependencyVector> vectors) { public DependencyResolver addVectors(@NotNull ImmutableLinkedList<? extends @NotNull DependencyVector> vectors) {
this.vectors.addAll(vectors); this.vectors.addAll(vectors);
resolved = false;
return this; return this;
} }
@ -117,10 +144,12 @@ public final class DependencyResolver {
* Adds multiple dependency vectors. * Adds multiple dependency vectors.
* *
* @param vectors dependency vectors to add * @param vectors dependency vectors to add
* @return itself
* @since 1-alpha1 * @since 1-alpha1
*/ */
public DependencyResolver addVectors(@NotNull Set<? extends @NotNull DependencyVector> vectors) { public DependencyResolver addVectors(@NotNull Set<? extends @NotNull DependencyVector> vectors) {
this.vectors.addAll(vectors); this.vectors.addAll(vectors);
resolved = false;
return this; return this;
} }
@ -128,11 +157,15 @@ public final class DependencyResolver {
* Resolves all dependency vectors. * Resolves all dependency vectors.
* Throws an exception when detecting an unmet dependency or a dependency cycle. * 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 * @since 1-alpha1
*/ */
@SuppressWarnings("JavaReflectionInvocation") @SuppressWarnings("JavaReflectionInvocation")
public DependencyResolver resolve() throws UnmetDependenciesException, UnexpectedThrowableException { public DependencyResolver resolve() throws UnmetDependenciesException, UnexpectedThrowableException {
Map<DependencyVector, String> unmetDependencies = new HashMap<>(); Map<DependencyVector, String> unmetDependencies = new HashMap<>();
resolved = false;
try { try {
for (DependencyVector vector : vectors) for (DependencyVector vector : vectors)
@ -216,6 +249,7 @@ public final class DependencyResolver {
if (!unmetDependencies.isEmpty()) if (!unmetDependencies.isEmpty())
throw new UnmetDependenciesException(unmetDependencies); throw new UnmetDependenciesException(unmetDependencies);
resolved = true;
return this; return this;
} }
@ -223,9 +257,13 @@ public final class DependencyResolver {
* Returns the correct order which stuff needs to be loaded/done in. * Returns the correct order which stuff needs to be loaded/done in.
* *
* @return {@link LinkedList} with dependencies first and dependents last * @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 * @since 1-alpha1
*/ */
public LinkedList<DependencyVector> getOrder() { public LinkedList<DependencyVector> getOrder() throws IllegalStateException {
if (!resolved)
throw new IllegalStateException("The current dependency vector list has not been resolved yet");
LinkedList<DependencyVector> list = new LinkedList<>(); LinkedList<DependencyVector> list = new LinkedList<>();
return list; return list;

View file

@ -49,7 +49,7 @@ public class Window implements de.staropensource.sosengine.graphics.classes.Wind
* -- GETTER -- * -- GETTER --
* Returns a set of all active windows. * Returns a set of all active windows.
* *
* @return set of all active windows * @return set of all windows
* @since 1-alpha0 * @since 1-alpha0
*/ */
@Getter @Getter