Heavily improve API doc of EngineConfiguration class
This commit is contained in:
parent
7560e150af
commit
69cf668c4d
GPG key ID:
E366BAEF67E4704D
1 changed files with 195 additions and 85 deletions
|
|
@ -19,8 +19,11 @@
|
|||
|
||||
package de.staropensource.engine.base;
|
||||
|
||||
import de.staropensource.engine.base.annotation.EngineSubsystem;
|
||||
import de.staropensource.engine.base.event.LogEvent;
|
||||
import de.staropensource.engine.base.implementable.Configuration;
|
||||
import de.staropensource.engine.base.implementable.ShortcodeParser;
|
||||
import de.staropensource.engine.base.implementable.SubsystemClass;
|
||||
import de.staropensource.engine.base.logging.Logger;
|
||||
import de.staropensource.engine.base.logging.backend.async.LoggingThread;
|
||||
import de.staropensource.engine.base.type.EngineState;
|
||||
|
|
@ -66,11 +69,11 @@ public final class EngineConfiguration extends Configuration {
|
|||
private static EngineConfiguration instance;
|
||||
|
||||
/**
|
||||
* Contains prefix properties must begin with.
|
||||
* Contains the configuration prefix.
|
||||
*
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Returns prefix properties must begin with.
|
||||
* Returns the configuration prefix.
|
||||
*
|
||||
* @return property group
|
||||
* @since v1-alpha0
|
||||
|
|
@ -79,132 +82,196 @@ public final class EngineConfiguration extends Configuration {
|
|||
|
||||
|
||||
/**
|
||||
* 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!
|
||||
* Contains if debugging options should be allowed.
|
||||
* All debugging options will be forcefully set to
|
||||
* {@code false} if this option is set to {@code false}.
|
||||
*
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #debug}.
|
||||
* Returns if debugging options should be allowed.
|
||||
* All debugging options will be forcefully set to
|
||||
* {@code false} if this option is set to {@code false}.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #debug
|
||||
* @return debugging enabled?
|
||||
* @since v1-alpha0
|
||||
*/
|
||||
private boolean debug;
|
||||
|
||||
/**
|
||||
* If enabled, all called events will be logged.
|
||||
* Contains whether or not to log
|
||||
* events being emitted.
|
||||
* <p>
|
||||
* This will cause all events to
|
||||
* be logged, with the exception
|
||||
* of the {@link LogEvent}.
|
||||
*
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #debugEvents}.
|
||||
* Returns whether or not to log
|
||||
* events being emitted.
|
||||
* <p>
|
||||
* This will cause all events to
|
||||
* be logged, with the exception
|
||||
* of the {@link LogEvent}.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #debugEvents
|
||||
* @return detailed event logging enabled?
|
||||
* @since v1-alpha0
|
||||
*/
|
||||
private boolean debugEvents;
|
||||
|
||||
|
||||
/**
|
||||
* If enabled, will try to automatically initialize every
|
||||
* subsystem found though reflection.
|
||||
* Contains whether or not to automatically discover
|
||||
* and initialize any class extending {@link SubsystemClass}
|
||||
* whilst being annotated with {@link EngineSubsystem}.
|
||||
* <p>
|
||||
* This however may fail in certain situation, where manual
|
||||
* subsystem initialization may be required. For this reason,
|
||||
* this can be turned off before the engine initializes. Please
|
||||
* note though that dependency resolution between subsystems
|
||||
* won't be performed, be careful when initializing subsystems manually.
|
||||
* This mechanism may fail in certain situations, where
|
||||
* manual subsystem initialization may be desired. Make
|
||||
* sure to disable this setting before engine startup
|
||||
* and then initialize all subsystems manually.
|
||||
*
|
||||
* @see Engine
|
||||
* @since v1-alpha2
|
||||
* @since v1-alpha5
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #initialPerformSubsystemInitialization}.
|
||||
* Returns whether or not to automatically discover
|
||||
* and initialize any class extending {@link SubsystemClass}
|
||||
* whilst being annotated with {@link EngineSubsystem}.
|
||||
* <p>
|
||||
* This mechanism may fail in certain situations, where
|
||||
* manual subsystem initialization may be desired. Make
|
||||
* sure to disable this setting before engine startup
|
||||
* and then initialize all subsystems manually.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #initialPerformSubsystemInitialization
|
||||
* @return automatically discover and initialize subsystems?
|
||||
* @since v1-alpha5
|
||||
*/
|
||||
private boolean initialPerformSubsystemInitialization;
|
||||
|
||||
/**
|
||||
* Will try to load the specified classes as subsystems,
|
||||
* if reflective classpath scanning is disabled.
|
||||
* Contains a set of class names to try to load
|
||||
* and initialize as subsystems. Will only take effect
|
||||
* if {@link #initialPerformSubsystemInitialization} is
|
||||
* turned off.
|
||||
*
|
||||
* @since v1-alpha5
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #initialIncludeSubsystemClasses}.
|
||||
* Returns a set of class names to try to load
|
||||
* and initialize as subsystems. Will only take effect
|
||||
* if {@link #getInitialIncludeSubsystemClasses()} is
|
||||
* turned off.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #initialIncludeSubsystemClasses
|
||||
* @return set of class names to try and initialize as subsystems
|
||||
* @since v1-alpha5
|
||||
*/
|
||||
private Set<@NotNull String> initialIncludeSubsystemClasses;
|
||||
|
||||
|
||||
/**
|
||||
* If enabled, will cause {@link ShortcodeParser} to print
|
||||
* invalid shortcodes as {@link LogLevel#SILENT_WARNING}s.
|
||||
* Contains whether or not to complain about invalid
|
||||
* shortcodes.
|
||||
* <p>
|
||||
* Requires the active log level to be set at least
|
||||
* to {@link LogLevel#SILENT_WARNING} to have effect.
|
||||
*
|
||||
* @see ShortcodeParser
|
||||
* @see #logLevel
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #errorShortcodeParser}.
|
||||
* Returns whether or not to complain about invalid
|
||||
* shortcodes.
|
||||
* <p>
|
||||
* Requires the active log level to be set at least
|
||||
* to {@link LogLevel#SILENT_WARNING} to have effect.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #errorShortcodeParser
|
||||
* @return complain about invalid shortcodes?
|
||||
* @see #getLogLevel()
|
||||
* @since v1-alpha0
|
||||
*/
|
||||
private boolean errorShortcodeParser;
|
||||
|
||||
|
||||
/**
|
||||
* If enabled, will makes the {@link Logger} work asynchronous,
|
||||
* in a separate platform thread. Don't disable unless you want
|
||||
* your application to run <b>extremely</b> slowly.
|
||||
* Contains if to log asynchronously.
|
||||
* <p>
|
||||
* If enabled, will cause a logging thread
|
||||
* to spawn. All log messages will be queued
|
||||
* and printed after a set delay
|
||||
* ({@link #logPollingSpeed}).
|
||||
* Highly recommended to keep enabled, or
|
||||
* the performance of your application will
|
||||
* very likely suffer.
|
||||
*
|
||||
* @see #logPollingSpeed
|
||||
* @see Thread
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #optimizeLogging}.
|
||||
* Returns if to log asynchronously.
|
||||
* <p>
|
||||
* If enabled, will cause a logging thread
|
||||
* to spawn. All log messages will be queued
|
||||
* and printed after a set delay
|
||||
* ({@link #getLogPollingSpeed()}).
|
||||
* Highly recommended to keep enabled, or
|
||||
* the performance of your application will
|
||||
* very likely suffer.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #optimizeLogging
|
||||
* @return log asynchronously?
|
||||
* @see #getLogPollingSpeed()
|
||||
* @since v1-alpha0
|
||||
*/
|
||||
private boolean optimizeLogging;
|
||||
|
||||
/**
|
||||
* If enabled, will make all events asynchronous,
|
||||
* in separate virtual threads. Don't disable unless you
|
||||
* want your application to run slower.
|
||||
* Contains whether or not to emit events
|
||||
* asynchronously.
|
||||
* <p>
|
||||
* This will cause a
|
||||
* <a href="https://openjdk.org/jeps/444">VirtualThread</a>
|
||||
* to spawn every time an event is emitted.
|
||||
*
|
||||
* @see VirtualThread
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #optimizeEvents}.
|
||||
* Contains whether or not to emit events
|
||||
* asynchronously.
|
||||
* <p>
|
||||
* This will cause a
|
||||
* <a href="https://openjdk.org/jeps/444">VirtualThread</a>
|
||||
* to spawn every time an event is emitted.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #optimizeEvents
|
||||
* @return emit events asynchronously?
|
||||
* @since v1-alpha0
|
||||
*/
|
||||
private boolean optimizeEvents;
|
||||
|
||||
|
||||
/**
|
||||
* Contains which logger levels are allowed
|
||||
* by setting the minimum logger level.
|
||||
* Contains the minimum allowed log level.
|
||||
* <p>
|
||||
* The priority list is as follows (from high to low priority):
|
||||
* <ul>
|
||||
* <li>{@link LogLevel#CRASH}</li>
|
||||
* <li>{@link LogLevel#ERROR}</li>
|
||||
* <li>{@link LogLevel#WARNING}</li>
|
||||
* <li>{@link LogLevel#INFORMATIONAL}</li>
|
||||
* <li>{@link LogLevel#SILENT_WARNING}</li>
|
||||
* <li>{@link LogLevel#VERBOSE}</li>
|
||||
* <li>{@link LogLevel#DIAGNOSTIC}</li>
|
||||
* </ul>
|
||||
*
|
||||
* @see Logger
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #logLevel}.
|
||||
* Returns the minimum allowed log level.
|
||||
* <p>
|
||||
* The priority list is as follows (from high to low priority):
|
||||
* <ul>
|
||||
* <li>{@link LogLevel#CRASH}</li>
|
||||
* <li>{@link LogLevel#ERROR}</li>
|
||||
* <li>{@link LogLevel#WARNING}</li>
|
||||
* <li>{@link LogLevel#INFORMATIONAL}</li>
|
||||
* <li>{@link LogLevel#SILENT_WARNING}</li>
|
||||
* <li>{@link LogLevel#VERBOSE}</li>
|
||||
* <li>{@link LogLevel#DIAGNOSTIC}</li>
|
||||
* </ul>
|
||||
*
|
||||
* @return variable value
|
||||
* @see #logLevel
|
||||
* @return minimum allowed log level
|
||||
* @since v1-alpha0
|
||||
*/
|
||||
private LogLevel logLevel;
|
||||
|
|
@ -226,75 +293,118 @@ public final class EngineConfiguration extends Configuration {
|
|||
* <li><code>lineNumber</code></li>
|
||||
* </ul>
|
||||
*
|
||||
* @see Logger
|
||||
* @since v1-alpha8
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #logFeatures}
|
||||
* Returns a comma-separated list of optional
|
||||
* features to add to the final log output.
|
||||
* <p>
|
||||
* Available features (in order of appearance):
|
||||
* <ul>
|
||||
* <li><code>formatting</code></li>
|
||||
* <li><code>runtime</code></li>
|
||||
* <li><code>date</code></li>
|
||||
* <li><code>time</code></li>
|
||||
* <li><code>shortIssuerClass</code></li>
|
||||
* <li><code>moduleName</code></li>
|
||||
* <li><code>moduleVersion</code> (requires <code>moduleName</code>)</li>
|
||||
* <li><code>methodName</code></li>
|
||||
* <li><code>lineNumber</code></li>
|
||||
* </ul>
|
||||
*
|
||||
* @return variable value
|
||||
* @see #logFeatures
|
||||
* @return optional features to enable
|
||||
* @since v1-alpha8
|
||||
*/
|
||||
private Set<@NotNull String> logFeatures;
|
||||
|
||||
/**
|
||||
* Contains how fast the logging thread will
|
||||
* poll for queued messages. This also causes
|
||||
* messages to be buffered.
|
||||
* poll for queued messages in milliseconds.
|
||||
* This also causes messages to be buffered.
|
||||
* <p>
|
||||
* Only applies if {@code optimizeLogging} is turned on.
|
||||
* Values below {@code 1} will poll for queued
|
||||
* messages as fast as it can. This however has pretty much
|
||||
* no benefit. Leave it at {@code 5}, it works quite well.
|
||||
* Values below {@code 1} will poll for queued messages
|
||||
* as fast as it can. This however has pretty much no
|
||||
* benefit. Leave it at {@code 5}, it works quite well.
|
||||
*
|
||||
* @see #optimizeLogging
|
||||
* @since v1-alpha4
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #logPollingSpeed}.
|
||||
* Contains how fast the logging thread will
|
||||
* poll for queued messages, in milliseconds.
|
||||
* This also causes messages to be buffered.
|
||||
* <p>
|
||||
* Only applies if {@code optimizeLogging} is turned on.
|
||||
* Values below {@code 1} will poll for queued messages
|
||||
* as fast as it can. This however has pretty much no
|
||||
* benefit. Leave it at {@code 5}, it works quite well.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #logPollingSpeed
|
||||
* @return logging thread polling speed in milliseconds
|
||||
* @see #isOptimizeLogging()
|
||||
* @since v1-alpha4
|
||||
*/
|
||||
private int logPollingSpeed;
|
||||
|
||||
/**
|
||||
* If enabled, will force sos!engine's logging infrastructure to use
|
||||
* <a href="https://www.man7.org/linux/man-pages/man3/stderr.3.html">the standard output</a>
|
||||
* instead of <a href="https://www.man7.org/linux/man-pages/man3/stderr.3.html">the standard error</a>
|
||||
* for logging the {@code ERROR} and {@code CRASH} log levels.
|
||||
* Contains whether or not to forcefully write
|
||||
* to the standard output instead of the
|
||||
* standard error stream.
|
||||
* <p>
|
||||
* This only applies to the {@link LogLevel#ERROR} and
|
||||
* {@link LogLevel#CRASH} log levels, as these use
|
||||
* the standard error stream by default.
|
||||
*
|
||||
* @see <a href="https://man7.org/linux/man-pages/man3/stderr.3.html">man page about standard streams</a>
|
||||
* @since v1-alpha0
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #logForceStandardOutput}.
|
||||
* Contains whether or not to forcefully write
|
||||
* to the standard output instead of the
|
||||
* standard error stream.
|
||||
* <p>
|
||||
* This only applies to the {@link LogLevel#ERROR} and
|
||||
* {@link LogLevel#CRASH} log levels, as these use
|
||||
* the standard error stream by default.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #logForceStandardOutput
|
||||
* @return force use stdout?
|
||||
* @see <a href="https://man7.org/linux/man-pages/man3/stderr.3.html">man page about standard streams</a>
|
||||
* @since v1-alpha0
|
||||
*/
|
||||
private boolean logForceStandardOutput;
|
||||
|
||||
|
||||
/**
|
||||
* Will truncate the path of types when using
|
||||
* their {@code toString} method.
|
||||
* Contains if to truncate the full path
|
||||
* of a class when invoking using their
|
||||
* {@link #toString()} method.
|
||||
* <p>
|
||||
* 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.engine.base.types.vectors.}{@link Vec2i}{@code (x=64 y=64)},
|
||||
* with it however it would just return
|
||||
* Here's an example: Lets say that you have a
|
||||
* {@link Vec2f} instance and want to convert
|
||||
* it to a String. You can do that by using
|
||||
* {@link Vec2f}'s {@link Vec2f#toString()}
|
||||
* method. With this flag disabled it will
|
||||
* return
|
||||
* {@code de.staropensource.engine.base.types.vectors.}{@link Vec2i}{@code (x=64 y=64)}.
|
||||
* With this flag enabled however the method will return
|
||||
* {@link Vec2i}{@code (x=64 y=64)},
|
||||
* which is much smaller.
|
||||
*
|
||||
* @since v1-alpha2
|
||||
* -- GETTER --
|
||||
* Gets the value for {@link #hideFullTypePath}.
|
||||
* Returns if to truncate the full path
|
||||
* of a class when invoking using their
|
||||
* {@link #toString()} method.
|
||||
* <p>
|
||||
* Here's an example: Lets say that you have a
|
||||
* {@link Vec2f} instance and want to convert
|
||||
* it to a String. You can do that by using
|
||||
* {@link Vec2f}'s {@link Vec2f#toString()}
|
||||
* method. With this flag disabled it will
|
||||
* return
|
||||
* {@code de.staropensource.engine.base.types.vectors.}{@link Vec2i}{@code (x=64 y=64)}.
|
||||
* With this flag enabled however the method will return
|
||||
* {@link Vec2i}{@code (x=64 y=64)},
|
||||
* which is much smaller.
|
||||
*
|
||||
* @return variable value
|
||||
* @see #hideFullTypePath
|
||||
* @return truncate class paths?
|
||||
* @since v1-alpha2
|
||||
*/
|
||||
private boolean hideFullTypePath;
|
||||
|
|
|
|||
Loading…
Reference in a new issue