diff --git a/docs/docs/getting-started/initializing.md b/docs/docs/getting-started/initializing.md index c26b69f9..516d23d5 100644 --- a/docs/docs/getting-started/initializing.md +++ b/docs/docs/getting-started/initializing.md @@ -1,7 +1,108 @@ --- sidebar_position: 1 -title: Initializing +title: Initializing the engine --- -# Initializing -## TODO +# Initializing the engine +To initialize the sos!engine, simply add this to the initialization code of your application: +```java +new Engine(); +``` + +This is enough to initialize the engine and all installed subsystems. No need to manually initialize them. + +## Printing something +Now you'll probably want to print some log output. Before you try using `System.out#println`, +`java.util.logging`, Log4J, SLFJ or some other logging library, please don't! The engine +provides it's own logging implementation and is HIGHLY recommended to be used instead. + +There are eight log levels you can use: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LevelDescription
DIAGNOSTICProvide detailed information about what is happening
VERBOSEAdditional information that may not be useful
SILENT_WARNINGWarnings that can be ignored or are caused by invalid (API) user input
INFORMATIONALUseful information about what is happening
WARNINGWarnings about dangerous or weird behaviour
ERRORNon-fatal errors
CRASHFatal errors which may or may not halt the running program (see below)
+ +Here's an example: +```java +Logger.info(new LogIssuer(Main.class), "Hello World!"); +``` + +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: +```java +class ExampleClass() { + @NotNull + private String string; + + public ExampleClass(@NotNull String string) { + this.string = string; + } + + public boolean checkForEscapes() { + Logger.diag(new LogIssuer(getClass(), string), "Checking for escapes"); + return string.contains("\\"); + } + + public boolean checkIfEmpty() { + Logger.diag(new LogIssuer(getClass(), 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`: +```java +class ExampleClass() { + @NotNull + private LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), string)); + + @NotNull + private String string; + + public ExampleClass(@NotNull String string) { + this.string = string; + } + + public boolean checkForEscapes() { + logger.diag("Checking for escapes"); + return string.contains("\\"); + } + + public boolean checkIfEmpty() { + logger.diag("Checking if empty"); + return string.isEmpty(); + } +} +``` + +As you can see, it's much simpler. No need to pass that to every call now!