Logging

All codes within The World Avatar project (TWA) should ensure they adequately use logging to record their actions and the occurrences of any warnings/errors. To that end, a common logging approach is presented below. Unless a specialist approach is needed for a particular code base, then it's expected that this approach is followed in all TWA projects.

Note: A previous logging framework is present in some older code bases; previously, the JPSBaseLogger class within the JPS Base Library was created with the intention that all codes would log through this central location, and that logs were remotely sent to a Servlet running using the JPS_BASE project. Whilst this JPSBaseLogger class still exists, it is now deprecated and should be avoided wherever possible. The logging Servlet provided by the JPS_BASE project is also not currently in use and should be avoided.

Logging in Java projects

Logging within all Java projects should now be handled via the use of Log4j2. Older versions of Log4j and SLF4J are now discouraged.

Log4j2 uses a configuration file to define the destination of logging statements, their format, and the minimum logging level. Two Log4j configuration files have been created for use with TWA Java code bases and can be downloaded from the package repository using Maven. See the Packages page of the Wiki for details on how to connect to the package repository.

Adding logging to your code

If you're starting a new Java code base, it's highly suggested that you take a copy of the example Java agent. This has already been configured to include the required libraries, download the config files, and contain example logging statements.

If adding (or updating) logging to an existing code base, simply follow the below steps.

1. Add the parent pom to your project.
2. Ensure the below dependencies are added to your project (any other logging libraries can be removed).

<dependency>
	<groupId>org.apache.logging.log4j</groupId>
	<artifactId>log4j-api</artifactId>
</dependency>
<dependency>
	<groupId>org.apache.logging.log4j</groupId>
	<artifactId>log4j-core</artifactId>
</dependency>

3. If using a Java project that builds as a WAR file (i.e. a Servlet), also include the following dependency.

<dependency>
	<groupId>org.apache.logging.log4j</groupId>
	<artifactId>log4j-web</artifactId>
</dependency>

4. Add the following plugins to your project's pom.xml file. If definitions of these plugins already exist in your project, their configuration should be merged with the one declared in the parent pom. If this causes issues, please contact senior developers.

<!-- Used to build into a WAR file and ensures everything in ./WEB-INF
gets copied into the final WAR file's internal WEB-INF directory. -->
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-war-plugin</artifactId>
	<!-- Version, configuration, and executions should be pulled from the 
	parent POM unless overridden here. -->
</plugin>

<!-- Downloads and extracts ZIP archives from Maven repository -->
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-dependency-plugin</artifactId>
	<!-- Version, configuration, and executions should be pulled from the 
	parent POM unless overridden here. -->
</plugin>