Recipe to migrate from JBoss Logging to SLF4J

[pdelagrave]

What problem are you trying to solve?

• Solve JBoss Logger support #220

What precondition(s) should be checked before applying this recipe?

Usage of the class org.jboss.logging.Logger

Before/After

Inspired from the existing migration recipes to SLF4J (JUL, log4j):

Dependencies

• Remove the org.jboss.logging:jboss-logging facade.
  • Only if none of the Message Bundle feature is used.
• Add the JBoss LogManager SLF4J binding/provider only if JBoss LogManager is the current logging backend.

Log Level mapping

JBoss Logging	SLF4J
TRACE	TRACE
DEBUG	DEBUG
INFO	INFO
WARN	WARN
ERROR	ERROR
FATAL	ERROR

Logging methods mapping

Using debug() as an example, but applies to all of:

• trace()
• debug()
• info()
• warn()
• error()
• fatal()
• log()

JBoss Logging	SLF4j
debug(Object message)	debug(String message)
debug(Object message, Throwable t)	debug(String msg, Throwable t)
debug(Object message, Object[] params)	debug(String msg, Object... arguments) See note 2
debug(Object message, Object[] params, Throwable t)	debug(String ms, Object... arguments) see note 2
debug(String loggerFqcn, Object message, Throwable t)	No SLF4J equivalent
debug(String loggerFqcn, Object message, Object[] params, Throwable t)	No SLF4J equivalent

• Note 1: The plan for No SLF4J equivalent methods is to leave them as is which will make the code uncompilable and require a manual fix. This is because SLF4J has no concept of an explicit/configurable FQCN, the caller's FQCN is always determined by SLF4J based on the callstack and cannot be changed.
• Note 2: Those are using the java.text.MessageFormat system, which is the same as the V methods (infov(), debugv(), etc). Their arguments will need to be converted first.

org.jboss.logging.Logger also has the f and v version of the methods:

• logger.debugf() to format the message using the String.format() formatter.
• logger.debugv() to format the message using the java.text.MessageFormat formatter. This is the same as JUL.

String.format() conversion

Suggested approach:

logger.infof("Hello %s, your total is %.2f", "john smith", 44.92);

becomes

logger.info("Hello {}, your total is {}", String.format("%s", "john smith"), String.format("%.2f", 44.92));

java.text.MessageFormat conversion

Suggested approach:
The JulParameterizedArguments JUL->SLF4J migration recipe already has the code to do that conversion, the idea would be to extract it into its own recipe or helper method so it can be re-used here.

Message Bundle

This is a feature specific to JBoss Logging and it can't be migrated to SLF4J.
We'll ensure that the migration of the Logger methods and changes of dependencies have no impact on the code using this feature.

Other methods

JBoss Logging	SLF4J
getName()	same
isDebugEnabled()	same
isTraceEnabled()	same
isInfoEnabled()	same
isEnabled(Level l)	use is*Level*Enabled() based on the level mapping specified above

Caviats

The org.jboss.logging:jboss-logging artifact include a JBoss Logging provider (backend) for all the well known logging systems: JUL, Log4j, Log4j2, SLF4J and JBoss Log Manager. These providers are guaranteed to respect/expect either the java.text.MessageFormat or String.format() depending on which Logger method is called. We can refactor based on that assumption.
However, we cannot safely apply the refactor on a codebase that would use a custom provider, as there's no guarantee that it'd respect the same convention.